Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 3 - Text Encoding Converter Reference / Text Encoding Converter Functions

Identifying Possible Destination Encodings /

TECGetDestinationTextEncodings

Returns the encoding specifications for all the destination text encodings to which the Text Encoding Converter can directly convert the specified source encoding.

pascal OSStatus TECGetDestinationTextEncodings (
                     TextEncoding inputEncoding,
                     TextEncoding destinationEncodings[],
                     ItemCount maxDestinationEncodings,
                     ItemCount *actualDestinationEncodings);

inputEncoding

The text encoding specification describing the source text.

destinationEncodings[]

An array of text encoding specifications. On return, this function fills the array elements with specifications for the destination encodings to which the converter can directly convert the source encoding given in the inputEncoding parameter. Your application allocates memory for this array to accommodate the encodings that this function returns. To determine how large an array to allocate, use the function TECCountDestinationTextEncodings (page 73).

maxDestinationEncodings

The maximum number of destination text encodings that the array can contain.

actualDestinationEncodings

A pointer to a value of type ItemCount. On return, this value indicates the number of text encoding specifications the function returned in the destination encodings array.

function result

A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) for a list of possible values. If other than noErr, then one of the text conversion plug-ins encountered an error when polled by the Text Encoding Converter.

DISCUSSION

The TECGetDestinationTextEncodings function returns text encoding specifications for the possible destination encodings in the array you pass as the directConversions parameter, eliminating any duplicate information in the process. Consequently, the number of encodings TECGetDestinationTextEncodings returns in the available encodings array may be fewer than the number of elements you allocated for the array based on your call to the function TECCountDestinationTextEncodings (page 73). TECGetDestinationTextEncodings tells you the number of specifications it returns in the actualDestinationEncodings parameter.

You can display the names of these destination encodings to the user if desired.